Well, here's one of those rare situations where it's ok to run the application before reading the read-me file. If you already have, the ToolBar manager is a set of routines that allow you to create toolbars like the ones you saw in the sample applications. The ToolBar Manager takes care of everything from creating the bar to handling user interactions which means you will not have to go through all the calculations I have had to do in the past few days.
What it requires?
The ToolBar manager uses QDOffscreen and Suite Icons (APDA Tech note# 306) so System 7 and Color QuickDraw is a requirement. As for RAM, requirements, that depends on how many "cells" you need to have on the bar. This is basically a trial and error thing.
ToolBar lingo and parts.
The ToolBar is made up of 2 parts that are closely linked together. The bar and the scrolling region. The bar is made up of cells that hold icons or picts. The scroll region has a thumb that is used for scrolling. The bar and the scroll can be anywhere in a window as long as they are within the same window.
ToolBar data.
There is one data structure that controls all aspects of a ToolBar. The TBHandle:
TBHandle^ = TBPtr
TBPtr^ =ToolBar
ToolBar = record
theWindow: WindowPtr;
theBar : CGrafPtr;
theScroll: CGrafPtr;
theBRect: Rect;
theSRect: Rect;
theVRect: Rect;
theVSRect: Rect;
thumbRect: Rect;
depth: Integer;
cells: Integer;
offset: Integer;
toffset: Integer;
inset: integer;
bkColor: RGBColor;
bwColor: Integer;
Cqd: Boolean;
end;
It is recommened that you do not access any of the fields directly. Instead use the routines discussed below.
Integer. Inset of each cell to invert when user clicks in it.
depth
Integer. Bit depth of ToolBar (0,1,2,4,8,24 or 32. 0 is best)
cTab
CTabHandle. Handle to color table for bar and scroll regions. Best to use windows color table.
cellP
PicHandle. Handle to PICT to represent an empty cell.
scrollP
PicHandle. Handle of PICT to be used a thumb in scroll region.
bkColor
RGBColor. Color of background of bar and scroll region.
bwColor
Integer. Color will be used if machine does not have Color QuickDraw.
returns:
Allocates space for and returns a TBHandle. Returns nil if error occured.
notes:
It is best that you make a PICT resource that holds the cell and thumb and make sure that the vertical size of bRect and sRect is that of the PICTs so that they will not have to be scalled. If so, they are only scalled vertically and not horiozontally.
• Drawing a toolbar.
procedure TBDraw (theToolBar);
theToolBar
TBHandle. Will draw the bar and scroll regions in the window the TBHandle is linked to (with TBCreate.)
notes:
Call this whenever you which to draw the whole bar and scroll region (like in an update procedure).
• Re-Drawing an individual cell.
procedure TBUpdateCell (theToolBar, theCell);
theToolBar
TBHandle.
theCell
Integer. Cell number to redraw.
notes:
Call this procedure if you wich to redraw the contents of a cell after you have made changes to it (see below how to do this.) It is better to call this as it updates an individual cell instead of the whole bar and scroll region, hence, reducing flicker.
• Plotting an ICN# into a cell
function TBPlotIcon (theToolBar, theCell, theIconID, theTransform, allignment): OsErr;
theToolBar
TBHandle.
theCell.
Integer. Cell to plot icon into.
theIconID.
Integer. ID of ICN# resource. (see below)
theTransform
Integer. Transformation to be applied.
allignment
Integer. Allignment of icon. (see below)
notes:
This call basically calls PlotIconID (described in detail in APDA Tech Note 306) and returns the error encountered by the call to PlotIconID. The 'theTransform' and 'allignment' parameters are as follows:
theTransform:
ttNone = $0000;
ttDisabled = $0001;
ttOffline = $0002;
ttOpen = $0003;
ttSelected = $4000;
ttSelectedDisabled = ttSelected + ttDisabled;
ttSelectedOffline = ttSelected + ttOffline;
ttSelectedOpen = ttSelected + ttOpen;
allignment:
aNone = $00;
aVerticalCenter = $01;
atTop = $02;
atBottom = $03;
aHorizontalCenter = $04;
atLeft = $08;
atRight = $0C;
To center an icon, pass aVerticalCenter + aHorizontalCenter. Call TBDraw or TBUpdateCell for changes to take effect.
The PICT will be drawn into the cell EXCLUDING the inset. It will also be centered. This can be used to erase a cell by passing the empty cell pict to the call. Call TBDraw or TBUpdateCell for changes to take effect.
• Drawing into a cell.
function TBGetCellRect (theToolBar; theCell);
theToolBar
TBHandle
theCell
Integer. Cell number.
returns:
A RECT. This is the bounds rect of the cell. You may use this RECT to use calls like CopyBits, DrawPicture etc etc.
notes:
This call is to be used to get the RECT of a given cell (without inset). The port holding the cells is "theBar" field of the TBHandle. This is the only time you should access/modify any field of the TBHandle. Be sure to call HLock to lock the TBHandle before dereferencing it. Call TBDraw or TBUpdateCell for changes to take effect.
Integer. If PicHandle is nil, TBDimPict looks for this ICN# to plot (PlotIconID).
allignment.
Integer. allignment of ICN# (if PicHandle is nil).
dimBy.
RGBColor. Color used for blending with CopyDeepMask.
doMask.
Boolean. If true, TBDimPict will calculate a mask using BitMapToRegion and pass it to CopyDeepMask.
notes:
This call allows you to create neat effects like a dimmed icon (see sample code and application). It draws the PICT/ICN# with the inset taken into consideration. Call TBDraw or TBUpdateCell for changes to take effect.
• Clearing a cell.
procedure TBClearCell (theToolBar; theCell);
theToolBar
TBHandle.
theCell
Integer. Cell to clear.
This call "clears" a cell by painting the cell with the RGBColor passed to TBCreate. Call TBDraw or TBUpdateCell for changes to take effect.
• Handling clicks in bar/scroll region.
function TBClick (theToolBar; theClick): integer;
theToolBar
TBHandle.
theClick
Point. Point where click initiated (local coordinates!)
returns:
Cell that was clicked in or -1 if scrolling occured or the user dragged the mouse out of the cell before letting go.
notes:
Call this function each time in your event loop for each ToolBar. You do not have to check to see if the user did indeed click in a bar or scroll region. It does nothing if the click was not in the toolbar. Otherwise, it handles all the scrolling, hiliting/unhiliting etc and returns control when the mouse is released. The call repeatedly calls GetMouse to track the mouse. It takes care of setting the port to the toolbar's window and re-sets the original port on exit. If the call returns a number other than -1, it is up to you to take action.
Rect. The new rect (In local coordinates) of the bar.
newSRect
Rect. The new rect (In local coordinates) of the scroll area.
notes
This call takes care of recalculating the new thumb locations etc for a toolbar. It is up to you to erase the original bar and scroll areas and you have to call TBDraw for changes to take effect (TBUpdateCell will not do here).
That is all there is to the ToolBar manager. The ToolBar Manager is not free. Read the 'License agreement' documentation for further information.
